/* 
 * FreeModbus Libary: A portable Modbus implementation for Modbus ASCII/RTU.
 * Copyright (c) 2006-2018 Christian Walter <cwalter@embedded-solutions.at>
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */

#ifndef _MB_UTILS_H
#define _MB_UTILS_H

#ifdef __cplusplus
PR_BEGIN_EXTERN_C
#endif
/*! \defgroup modbus_utils 工具
 *
 * 本模块包含一些可供应用程序使用的实用函数。其中包括一些用于处理由字符数组缓冲区支持的位域的特殊函数。
 *
 */
/*! \addtogroup modbus_utils
 *  @{
 */
/*! \brief 在字节缓冲区中设置位的函数。
 *
 * 此函数能高效利用数组来实现位域。用于存储位的数组必须始终是两字节的倍数。一次操作最多可设置或清除八个位。
 *
 * \param ucByteBuf 一个存储位值的缓冲区。其大小必须是2字节的倍数。不执行长度检查，并且如果usBitOffset / 8大于缓冲区大小，内存内容将被覆盖。
 * \param usBitOffset The starting address of the bits to set. The first  bit has the offset 0.
 * \param ucNBits Number of bits to modify. The value must always be smaller than 8.
 * \param ucValues 这些是位的新值。从usBitOffset开始的第一个位的值是ucValues值的最低有效位。
 *
 * \code
 * ucBits[2] = {0, 0};
 *
 * // 将位4设置为1（解读：从位偏移量4开始，将1个位设置为值1）
 * WHT_MB_Util_Set_Bits(ucBits, 4, 1, 1);
 *
 * // 将位7设为1，位8设为0
 * WHT_MB_Util_Set_Bits(ucBits, 7, 2, 0x01);
 *
 * // 将第8-11位设置为0x05，将第12-15位设置为0x0A；
 * WHT_MB_Util_Set_Bits( ucBits, 8, 8, 0x5A);
 * \endcode
 */
void WHT_MB_Util_Set_Bits(uint8_t* ucByteBuf, uint16_t usBitOffset, uint8_t ucNBits, uint8_t ucValues);

/*! \brief 读取字节缓冲区中比特的函数。
 *
 * 此函数用于从数组中提取高位值。一次最多可以提取8个高位值。
 *
 * \param ucByteBuf 一个存储位值的缓冲区。
 * \param usBitOffset 要设置的位的起始地址。第一位的偏移量为0。
 * \param ucNBits 要修改的位数。该值必须始终小于8。
 *
 * \code
 * uint8_t ucBits[2] = {0, 0};
 * uint8_t ucResult;
 *
 * // 提取第3到第10位的比特。
 * ucResult = WHT_MB_Util_Get_Bits( ucBits, 3, 8 );
 * \endcode
 */
uint8_t WHT_MB_Util_Get_Bits(uint8_t* ucByteBuf, uint16_t usBitOffset, uint8_t ucNBits);

/*! @} */

#ifdef __cplusplus
PR_END_EXTERN_C
#endif
#endif
